includes/filerepo/FileRepo.php

   1 <?php
   2 /**
   3  * Base code for file repositories.
   4  *
   5  * @file
   6  * @ingroup FileRepo
   7  */
   8
   9 /**
  10  * Base class for file repositories
  11  *
  12  * @ingroup FileRepo
  13  */
  14 class FileRepo {
  15         const FILES_ONLY = 1;
  16
  17         const DELETE_SOURCE = 1;
  18         const OVERWRITE = 2;
  19         const OVERWRITE_SAME = 4;
  20         const SKIP_LOCKING = 8;
  21
  22         /** @var FileBackendBase */
  23         protected $backend;
  24         /** @var Array Map of zones to config */
  25         protected $zones = array();
  26
  27         var $thumbScriptUrl, $transformVia404;
  28         var $descBaseUrl, $scriptDirUrl, $scriptExtension, $articleUrl;
  29         var $fetchDescription, $initialCapital;
  30         var $pathDisclosureProtection = 'simple'; // 'paranoid'
  31         var $descriptionCacheExpiry, $url, $thumbUrl;
  32         var $hashLevels, $deletedHashLevels;
  33
  34         /**
  35          * Factory functions for creating new files
  36          * Override these in the base class
  37          */
  38         var $fileFactory = array( 'UnregisteredLocalFile', 'newFromTitle' );
  39         var $oldFileFactory = false;
  40         var $fileFactoryKey = false, $oldFileFactoryKey = false;
  41
  42         function __construct( $info ) {
  43                 // Required settings
  44                 $this->name = $info['name'];
  45                 if ( $info['backend'] instanceof FileBackendBase ) {
  46                         $this->backend = $info['backend']; // useful for testing
  47                 } else {
  48                         $this->backend = FileBackendGroup::singleton()->get( $info['backend'] );
  49                 }
  50
  51                 // Optional settings that can have no value
  52                 $optionalSettings = array(
  53                         'descBaseUrl', 'scriptDirUrl', 'articleUrl', 'fetchDescription',
  54                         'thumbScriptUrl', 'pathDisclosureProtection', 'descriptionCacheExpiry',
  55                         'scriptExtension'
  56                 );
  57                 foreach ( $optionalSettings as $var ) {
  58                         if ( isset( $info[$var] ) ) {
  59                                 $this->$var = $info[$var];
  60                         }
  61                 }
  62
  63                 // Optional settings that have a default
  64                 $this->initialCapital = isset( $info['initialCapital'] )
  65                         ? $info['initialCapital']
  66                         : MWNamespace::isCapitalized( NS_FILE );
  67                 $this->url = isset( $info['url'] )
  68                         ? $info['url']
  69                         : false; // a subclass may set the URL (e.g. ForeignAPIRepo)
  70                 if ( isset( $info['thumbUrl'] ) ) {
  71                         $this->thumbUrl = $info['thumbUrl'];
  72                 } else {
  73                         $this->thumbUrl = $this->url ? "{$this->url}/thumb" : false;
  74                 }
  75                 $this->hashLevels = isset( $info['hashLevels'] )
  76                         ? $info['hashLevels']
  77                         : 2;
  78                 $this->deletedHashLevels = isset( $info['deletedHashLevels'] )
  79                         ? $info['deletedHashLevels']
  80                         : $this->hashLevels;
  81                 $this->transformVia404 = !empty( $info['transformVia404'] );
  82                 $this->zones = isset( $info['zones'] )
  83                         ? $info['zones']
  84                         : array();
  85                 // Give defaults for the basic zones...
  86                 foreach ( array( 'public', 'thumb', 'temp', 'deleted' ) as $zone ) {
  87                         if ( !isset( $this->zones[$zone] ) ) {
  88                                 if ( $zone === 'deleted' ) {
  89                                         $this->zones[$zone] = array(
  90                                                 'container' => null, // user must set this up
  91                                                 'directory' => '' // container root
  92                                         );
  93                                 } else {
  94                                         $this->zones[$zone] = array(
  95                                                 'container' => "media-$zone",
  96                                                 'directory' => '' // container root
  97                                         );
  98                                 }
  99                         }
 100                 }
 101         }
 102
 103         /**
 104          * Get the file backend instance
 105          *
 106          * @return FileBackendBase
 107          */
 108         public function getBackend() {
 109                 return $this->backend;
 110         }
 111
 112         /**
 113          * Prepare all the zones for basic usage.
 114          * See initDeletedDir() for additional setup needed for the 'deleted' zone.
 115          *
 116          * @param $doZones Array Only do a particular zones
 117          * @return Status
 118          */
 119         protected function initZones( $doZones = array() ) {
 120                 $status = $this->newGood();
 121                 $doZones = (array)$doZones; // string => array
 122                 foreach ( $this->zones as $zone => $info ) {
 123                         if ( $doZones && !in_array( $zone, $doZones ) ) {
 124                                 continue;
 125                         }
 126                         $root = $this->getZonePath( $zone );
 127                         if ( $root !== null ) {
 128                                 $params = array( 'dir' => $this->getZonePath( $zone ) );
 129                                 $status->merge( $this->backend->prepare( $params ) );
 130                         }
 131                 }
 132                 return $status;
 133         }
 134
 135         /**
 136          * Take all available measures to prevent web accessibility of new deleted
 137          * directories, in case the user has not configured offline storage
 138          *
 139          * @return void
 140          */
 141         protected function initDeletedDir( $dir ) {
 142                 // Add a .htaccess file to the root of the deleted zone
 143                 $root = $this->getZonePath( 'deleted' );
 144                 $this->backend->secure( array( 'dir' => $root, 'noAccess' => true ) );
 145                 // Seed new directories with a blank index.html, to prevent crawling
 146                 $this->backend->secure( array( 'dir' => $dir, 'noListing' => true ) );
 147         }
 148
 149         /**
 150          * Determine if a string is an mwrepo:// URL
 151          *
 152          * @param $url string
 153          * @return bool
 154          */
 155         public static function isVirtualUrl( $url ) {
 156                 return substr( $url, 0, 9 ) == 'mwrepo://';
 157         }
 158
 159         /**
 160          * Get a URL referring to this repository, with the private mwrepo protocol.
 161          * The suffix, if supplied, is considered to be unencoded, and will be
 162          * URL-encoded before being returned.
 163          *
 164          * @param $suffix string
 165          * @return string
 166          */
 167         public function getVirtualUrl( $suffix = false ) {
 168                 $path = 'mwrepo://' . $this->name;
 169                 if ( $suffix !== false ) {
 170                         $path .= '/' . rawurlencode( $suffix );
 171                 }
 172                 return $path;
 173         }
 174
 175         /**
 176          * Get the URL corresponding to one of the four basic zones
 177          *
 178          * @param $zone String: one of: public, deleted, temp, thumb
 179          * @return String or false
 180          */
 181         public function getZoneUrl( $zone ) {
 182                 switch ( $zone ) {
 183                         case 'public':
 184                                 return $this->url;
 185                         case 'temp':
 186                                 return "{$this->url}/temp";
 187                         case 'deleted':
 188                                 return false; // no public URL
 189                         case 'thumb':
 190                                 return $this->thumbUrl;
 191                         default:
 192                                 return false;
 193                 }
 194         }
 195
 196         /**
 197          * Get the backend storage path corresponding to a virtual URL
 198          *
 199          * @param $url string
 200          * @return string
 201          */
 202         function resolveVirtualUrl( $url ) {
 203                 if ( substr( $url, 0, 9 ) != 'mwrepo://' ) {
 204                         throw new MWException( __METHOD__.': unknown protocol' );
 205                 }
 206                 $bits = explode( '/', substr( $url, 9 ), 3 );
 207                 if ( count( $bits ) != 3 ) {
 208                         throw new MWException( __METHOD__.": invalid mwrepo URL: $url" );
 209                 }
 210                 list( $repo, $zone, $rel ) = $bits;
 211                 if ( $repo !== $this->name ) {
 212                         throw new MWException( __METHOD__.": fetching from a foreign repo is not supported" );
 213                 }
 214                 $base = $this->getZonePath( $zone );
 215                 if ( !$base ) {
 216                         throw new MWException( __METHOD__.": invalid zone: $zone" );
 217                 }
 218                 return $base . '/' . rawurldecode( $rel );
 219         }
 220
 221         /**
 222          * The the storage container and base path of a zone
 223          *
 224          * @param $zone string
 225          * @return Array (container, base path) or (null, null)
 226          */
 227         protected function getZoneLocation( $zone ) {
 228                 if ( !isset( $this->zones[$zone] ) ) {
 229                         return array( null, null ); // bogus
 230                 }
 231                 return array( $this->zones[$zone]['container'], $this->zones[$zone]['directory'] );
 232         }
 233
 234         /**
 235          * Get the storage path corresponding to one of the zones
 236          *
 237          * @param $zone string
 238          * @return string|null
 239          */
 240         public function getZonePath( $zone ) {
 241                 list( $container, $base ) = $this->getZoneLocation( $zone );
 242                 if ( $container === null || $base === null ) {
 243                         return null;
 244                 }
 245                 $backendName = $this->backend->getName();
 246                 if ( $base != '' ) { // may not be set
 247                         $base = "/{$base}";
 248                 }
 249                 return "mwstore://$backendName/{$container}{$base}";
 250         }
 251
 252         /**
 253          * Create a new File object from the local repository
 254          *
 255          * @param $title Mixed: Title object or string
 256          * @param $time Mixed: Time at which the image was uploaded.
 257          *              If this is specified, the returned object will be an
 258          *              instance of the repository's old file class instead of a
 259          *              current file. Repositories not supporting version control
 260          *              should return false if this parameter is set.
 261          * @return File|null A File, or null if passed an invalid Title
 262          */
 263         public function newFile( $title, $time = false ) {
 264                 $title = File::normalizeTitle( $title );
 265                 if ( !$title ) {
 266                         return null;
 267                 }
 268                 if ( $time ) {
 269                         if ( $this->oldFileFactory ) {
 270                                 return call_user_func( $this->oldFileFactory, $title, $this, $time );
 271                         } else {
 272                                 return false;
 273                         }
 274                 } else {
 275                         return call_user_func( $this->fileFactory, $title, $this );
 276                 }
 277         }
 278
 279         /**
 280          * Find an instance of the named file created at the specified time
 281          * Returns false if the file does not exist. Repositories not supporting
 282          * version control should return false if the time is specified.
 283          *
 284          * @param $title Mixed: Title object or string
 285          * @param $options array Associative array of options:
 286          *     time:           requested time for an archived image, or false for the
 287          *                     current version. An image object will be returned which was
 288          *                     created at the specified time.
 289          *
 290          *     ignoreRedirect: If true, do not follow file redirects
 291          *
 292          *     private:        If true, return restricted (deleted) files if the current
 293          *                     user is allowed to view them. Otherwise, such files will not
 294          *                     be found.
 295          * @return File|false
 296          */
 297         public function findFile( $title, $options = array() ) {
 298                 $title = File::normalizeTitle( $title );
 299                 if ( !$title ) {
 300                         return false;
 301                 }
 302                 $time = isset( $options['time'] ) ? $options['time'] : false;
 303                 # First try the current version of the file to see if it precedes the timestamp
 304                 $img = $this->newFile( $title );
 305                 if ( !$img ) {
 306                         return false;
 307                 }
 308                 if ( $img->exists() && ( !$time || $img->getTimestamp() == $time ) ) {
 309                         return $img;
 310                 }
 311                 # Now try an old version of the file
 312                 if ( $time !== false ) {
 313                         $img = $this->newFile( $title, $time );
 314                         if ( $img && $img->exists() ) {
 315                                 if ( !$img->isDeleted( File::DELETED_FILE ) ) {
 316                                         return $img; // always OK
 317                                 } elseif ( !empty( $options['private'] ) && $img->userCan( File::DELETED_FILE ) ) {
 318                                         return $img;
 319                                 }
 320                         }
 321                 }
 322
 323                 # Now try redirects
 324                 if ( !empty( $options['ignoreRedirect'] ) ) {
 325                         return false;
 326                 }
 327                 $redir = $this->checkRedirect( $title );
 328                 if ( $redir && $title->getNamespace() == NS_FILE) {
 329                         $img = $this->newFile( $redir );
 330                         if ( !$img ) {
 331                                 return false;
 332                         }
 333                         if ( $img->exists() ) {
 334                                 $img->redirectedFrom( $title->getDBkey() );
 335                                 return $img;
 336                         }
 337                 }
 338                 return false;
 339         }
 340
 341         /**
 342          * Find many files at once.
 343          *
 344          * @param $items An array of titles, or an array of findFile() options with
 345          *    the "title" option giving the title. Example:
 346          *
 347          *     $findItem = array( 'title' => $title, 'private' => true );
 348          *     $findBatch = array( $findItem );
 349          *     $repo->findFiles( $findBatch );
 350          * @return array
 351          */
 352         public function findFiles( $items ) {
 353                 $result = array();
 354                 foreach ( $items as $item ) {
 355                         if ( is_array( $item ) ) {
 356                                 $title = $item['title'];
 357                                 $options = $item;
 358                                 unset( $options['title'] );
 359                         } else {
 360                                 $title = $item;
 361                                 $options = array();
 362                         }
 363                         $file = $this->findFile( $title, $options );
 364                         if ( $file ) {
 365                                 $result[$file->getTitle()->getDBkey()] = $file;
 366                         }
 367                 }
 368                 return $result;
 369         }
 370
 371         /**
 372          * Find an instance of the file with this key, created at the specified time
 373          * Returns false if the file does not exist. Repositories not supporting
 374          * version control should return false if the time is specified.
 375          *
 376          * @param $sha1 String base 36 SHA-1 hash
 377          * @param $options Option array, same as findFile().
 378          * @return File|false
 379          */
 380         public function findFileFromKey( $sha1, $options = array() ) {
 381                 $time = isset( $options['time'] ) ? $options['time'] : false;
 382
 383                 # First try to find a matching current version of a file...
 384                 if ( $this->fileFactoryKey ) {
 385                         $img = call_user_func( $this->fileFactoryKey, $sha1, $this, $time );
 386                 } else {
 387                         return false; // find-by-sha1 not supported
 388                 }
 389                 if ( $img && $img->exists() ) {
 390                         return $img;
 391                 }
 392                 # Now try to find a matching old version of a file...
 393                 if ( $time !== false && $this->oldFileFactoryKey ) { // find-by-sha1 supported?
 394                         $img = call_user_func( $this->oldFileFactoryKey, $sha1, $this, $time );
 395                         if ( $img && $img->exists() ) {
 396                                 if ( !$img->isDeleted( File::DELETED_FILE ) ) {
 397                                         return $img; // always OK
 398                                 } elseif ( !empty( $options['private'] ) && $img->userCan( File::DELETED_FILE ) ) {
 399                                         return $img;
 400                                 }
 401                         }
 402                 }
 403                 return false;
 404         }
 405
 406         /**
 407          * Get an array or iterator of file objects for files that have a given
 408          * SHA-1 content hash.
 409          *
 410          * STUB
 411          */
 412         public function findBySha1( $hash ) {
 413                 return array();
 414         }
 415
 416         /**
 417          * Get the public root URL of the repository
 418          *
 419          * @return string|false
 420          */
 421         public function getRootUrl() {
 422                 return $this->url;
 423         }
 424
 425         /**
 426          * Returns true if the repository uses a multi-level directory structure
 427          *
 428          * @return string
 429          */
 430         public function isHashed() {
 431                 return (bool)$this->hashLevels;
 432         }
 433
 434         /**
 435          * Get the URL of thumb.php
 436          *
 437          * @return string
 438          */
 439         public function getThumbScriptUrl() {
 440                 return $this->thumbScriptUrl;
 441         }
 442
 443         /**
 444          * Returns true if the repository can transform files via a 404 handler
 445          *
 446          * @return bool
 447          */
 448         public function canTransformVia404() {
 449                 return $this->transformVia404;
 450         }
 451
 452         /**
 453          * Get the name of an image from its title object
 454          *
 455          * @param $title Title
 456          */
 457         public function getNameFromTitle( Title $title ) {
 458                 global $wgContLang;
 459                 if ( $this->initialCapital != MWNamespace::isCapitalized( NS_FILE ) ) {
 460                         $name = $title->getUserCaseDBKey();
 461                         if ( $this->initialCapital ) {
 462                                 $name = $wgContLang->ucfirst( $name );
 463                         }
 464                 } else {
 465                         $name = $title->getDBkey();
 466                 }
 467                 return $name;
 468         }
 469
 470         /**
 471          * Get the public zone root storage directory of the repository
 472          *
 473          * @return string
 474          */
 475         public function getRootDirectory() {
 476                 return $this->getZonePath( 'public' );
 477         }
 478
 479         /**
 480          * Get a relative path including trailing slash, e.g. f/fa/
 481          * If the repo is not hashed, returns an empty string
 482          *
 483          * @param $name string
 484          * @return string
 485          */
 486         public function getHashPath( $name ) {
 487                 return self::getHashPathForLevel( $name, $this->hashLevels );
 488         }
 489
 490         /**
 491          * @param $name
 492          * @param $levels
 493          * @return string
 494          */
 495         static function getHashPathForLevel( $name, $levels ) {
 496                 if ( $levels == 0 ) {
 497                         return '';
 498                 } else {
 499                         $hash = md5( $name );
 500                         $path = '';
 501                         for ( $i = 1; $i <= $levels; $i++ ) {
 502                                 $path .= substr( $hash, 0, $i ) . '/';
 503                         }
 504                         return $path;
 505                 }
 506         }
 507
 508         /**
 509          * Get the number of hash directory levels
 510          *
 511          * @return integer
 512          */
 513         public function getHashLevels() {
 514                 return $this->hashLevels;
 515         }
 516
 517         /**
 518          * Get the name of this repository, as specified by $info['name]' to the constructor
 519          *
 520          * @return string
 521          */
 522         public function getName() {
 523                 return $this->name;
 524         }
 525
 526         /**
 527          * Make an url to this repo
 528          *
 529          * @param $query mixed Query string to append
 530          * @param $entry string Entry point; defaults to index
 531          * @return string|false
 532          */
 533         public function makeUrl( $query = '', $entry = 'index' ) {
 534                 if ( isset( $this->scriptDirUrl ) ) {
 535                         $ext = isset( $this->scriptExtension ) ? $this->scriptExtension : '.php';
 536                         return wfAppendQuery( "{$this->scriptDirUrl}/{$entry}{$ext}", $query );
 537                 }
 538                 return false;
 539         }
 540
 541         /**
 542          * Get the URL of an image description page. May return false if it is
 543          * unknown or not applicable. In general this should only be called by the
 544          * File class, since it may return invalid results for certain kinds of
 545          * repositories. Use File::getDescriptionUrl() in user code.
 546          *
 547          * In particular, it uses the article paths as specified to the repository
 548          * constructor, whereas local repositories use the local Title functions.
 549          *
 550          * @param $name string
 551          * @return string
 552          */
 553         public function getDescriptionUrl( $name ) {
 554                 $encName = wfUrlencode( $name );
 555                 if ( !is_null( $this->descBaseUrl ) ) {
 556                         # "http://example.com/wiki/Image:"
 557                         return $this->descBaseUrl . $encName;
 558                 }
 559                 if ( !is_null( $this->articleUrl ) ) {
 560                         # "http://example.com/wiki/$1"
 561                         #
 562                         # We use "Image:" as the canonical namespace for
 563                         # compatibility across all MediaWiki versions.
 564                         return str_replace( '$1',
 565                                 "Image:$encName", $this->articleUrl );
 566                 }
 567                 if ( !is_null( $this->scriptDirUrl ) ) {
 568                         # "http://example.com/w"
 569                         #
 570                         # We use "Image:" as the canonical namespace for
 571                         # compatibility across all MediaWiki versions,
 572                         # and just sort of hope index.php is right. ;)
 573                         return $this->makeUrl( "title=Image:$encName" );
 574                 }
 575                 return false;
 576         }
 577
 578         /**
 579          * Get the URL of the content-only fragment of the description page. For
 580          * MediaWiki this means action=render. This should only be called by the
 581          * repository's file class, since it may return invalid results. User code
 582          * should use File::getDescriptionText().
 583          *
 584          * @param $name String: name of image to fetch
 585          * @param $lang String: language to fetch it in, if any.
 586          * @return string
 587          */
 588         public function getDescriptionRenderUrl( $name, $lang = null ) {
 589                 $query = 'action=render';
 590                 if ( !is_null( $lang ) ) {
 591                         $query .= '&uselang=' . $lang;
 592                 }
 593                 if ( isset( $this->scriptDirUrl ) ) {
 594                         return $this->makeUrl(
 595                                 'title=' .
 596                                 wfUrlencode( 'Image:' . $name ) .
 597                                 "&$query" );
 598                 } else {
 599                         $descUrl = $this->getDescriptionUrl( $name );
 600                         if ( $descUrl ) {
 601                                 return wfAppendQuery( $descUrl, $query );
 602                         } else {
 603                                 return false;
 604                         }
 605                 }
 606         }
 607
 608         /**
 609          * Get the URL of the stylesheet to apply to description pages
 610          *
 611          * @return string|false
 612          */
 613         public function getDescriptionStylesheetUrl() {
 614                 if ( isset( $this->scriptDirUrl ) ) {
 615                         return $this->makeUrl( 'title=MediaWiki:Filepage.css&' .
 616                                 wfArrayToCGI( Skin::getDynamicStylesheetQuery() ) );
 617                 }
 618                 return false;
 619         }
 620
 621         /**
 622          * Store a file to a given destination.
 623          *
 624          * @param $srcPath String: source FS path, storage path, or virtual URL
 625          * @param $dstZone String: destination zone
 626          * @param $dstRel String: destination relative path
 627          * @param $flags Integer: bitwise combination of the following flags:
 628          *     self::DELETE_SOURCE     Delete the source file after upload
 629          *     self::OVERWRITE         Overwrite an existing destination file instead of failing
 630          *     self::OVERWRITE_SAME    Overwrite the file if the destination exists and has the
 631          *                             same contents as the source
 632          *     self::SKIP_LOCKING      Skip any file locking when doing the store
 633          * @return FileRepoStatus
 634          */
 635         public function store( $srcPath, $dstZone, $dstRel, $flags = 0 ) {
 636                 $status = $this->storeBatch( array( array( $srcPath, $dstZone, $dstRel ) ), $flags );
 637                 if ( $status->successCount == 0 ) {
 638                         $status->ok = false;
 639                 }
 640                 return $status;
 641         }
 642
 643         /**
 644          * Store a batch of files
 645          *
 646          * @param $triplets Array: (src, dest zone, dest rel) triplets as per store()
 647          * @param $flags Integer: bitwise combination of the following flags:
 648          *     self::DELETE_SOURCE     Delete the source file after upload
 649          *     self::OVERWRITE         Overwrite an existing destination file instead of failing
 650          *     self::OVERWRITE_SAME    Overwrite the file if the destination exists and has the
 651          *                             same contents as the source
 652          *     self::SKIP_LOCKING      Skip any file locking when doing the store
 653          * @return FileRepoStatus
 654          */
 655         public function storeBatch( $triplets, $flags = 0 ) {
 656                 $backend = $this->backend; // convenience
 657
 658                 $status = $this->newGood();
 659
 660                 $operations = array();
 661                 $sourceFSFilesToDelete = array(); // cleanup for disk source files
 662                 // Validate each triplet and get the store operation...
 663                 foreach ( $triplets as $i => $triplet ) {
 664                         list( $srcPath, $dstZone, $dstRel ) = $triplet;
 665
 666                         // Resolve destination path
 667                         $root = $this->getZonePath( $dstZone );
 668                         if ( !$root ) {
 669                                 throw new MWException( "Invalid zone: $dstZone" );
 670                         }
 671                         if ( !$this->validateFilename( $dstRel ) ) {
 672                                 throw new MWException( 'Validation error in $dstRel' );
 673                         }
 674                         $dstPath = "$root/$dstRel";
 675                         $dstDir = dirname( $dstPath );
 676
 677                         // Create destination directories for this triplet
 678                         if ( !$backend->prepare( array( 'dir' => $dstDir ) )->isOK() ) {
 679                                 return $this->newFatal( 'directorycreateerror', $dstDir );
 680                         }
 681
 682                         if ( $dstZone == 'deleted' ) {
 683                                 $this->initDeletedDir( $dstDir );
 684                         }
 685
 686                         // Resolve source to a storage path if virtual
 687                         if ( self::isVirtualUrl( $srcPath ) ) {
 688                                 $srcPath = $this->resolveVirtualUrl( $srcPath );
 689                         }
 690
 691                         // Get the appropriate file operation
 692                         if ( FileBackend::isStoragePath( $srcPath ) ) {
 693                                 $opName = ( $flags & self::DELETE_SOURCE ) ? 'move' : 'copy';
 694                         } else {
 695                                 $opName = 'store';
 696                                 if ( $flags & self::DELETE_SOURCE ) {
 697                                         $sourceFSFilesToDelete[] = $srcPath;
 698                                 }
 699                         }
 700                         $operations[] = array(
 701                                 'op'            => $opName,
 702                                 'src'           => $srcPath,
 703                                 'dst'           => $dstPath,
 704                                 'overwriteDest' => $flags & self::OVERWRITE,
 705                                 'overwriteSame' => $flags & self::OVERWRITE_SAME,
 706                         );
 707                 }
 708
 709                 // Execute the store operation for each triplet
 710                 $opts = array( 'ignoreErrors' => true );
 711                 if ( $flags & self::SKIP_LOCKING ) {
 712                         $opts['nonLocking'] = true;
 713                 }
 714                 $status->merge( $backend->doOperations( $operations, $opts ) );
 715                 // Cleanup for disk source files...
 716                 foreach ( $sourceFSFilesToDelete as $file ) {
 717                         wfSuppressWarnings();
 718                         unlink( $file ); // FS cleanup
 719                         wfRestoreWarnings();
 720                 }
 721
 722                 return $status;
 723         }
 724
 725         /**
 726          * Deletes a batch of files.
 727          * Each file can be a (zone, rel) pair, virtual url, storage path, or FS path.
 728          * It will try to delete each file, but ignores any errors that may occur.
 729          *
 730          * @param $pairs array List of files to delete
 731          * @return void
 732          */
 733         public function cleanupBatch( $files ) {
 734                 $operations = array();
 735                 $sourceFSFilesToDelete = array(); // cleanup for disk source files
 736                 foreach ( $files as $file ) {
 737                         if ( is_array( $file ) ) {
 738                                 // This is a pair, extract it
 739                                 list( $zone, $rel ) = $file;
 740                                 $root = $this->getZonePath( $zone );
 741                                 $path = "$root/$rel";
 742                         } else {
 743                                 if ( self::isVirtualUrl( $file ) ) {
 744                                         // This is a virtual url, resolve it
 745                                         $path = $this->resolveVirtualUrl( $file );
 746                                 } else {
 747                                         // This is a full file name
 748                                         $path = $file;
 749                                 }
 750                         }
 751                         // Get a file operation if needed
 752                         if ( FileBackend::isStoragePath( $path ) ) {
 753                                 $operations[] = array(
 754                                         'op'           => 'delete',
 755                                         'src'          => $path,
 756                                 );
 757                         } else {
 758                                 $sourceFSFilesToDelete[] = $path;
 759                         }
 760                 }
 761                 // Actually delete files from storage...
 762                 $opts = array( 'ignoreErrors' => true );
 763                 $this->backend->doOperations( $operations, $opts );
 764                 // Cleanup for disk source files...
 765                 foreach ( $sourceFSFilesToDelete as $file ) {
 766                         wfSuppressWarnings();
 767                         unlink( $path ); // FS cleanup
 768                         wfRestoreWarnings();
 769                 }
 770         }
 771
 772         /**
 773          * Pick a random name in the temp zone and store a file to it.
 774          * Returns a FileRepoStatus object with the URL in the value.
 775          *
 776          * @param $originalName String: the base name of the file as specified
 777          *     by the user. The file extension will be maintained.
 778          * @param $srcPath String: the current location of the file.
 779          * @return FileRepoStatus object with the URL in the value.
 780          */
 781         public function storeTemp( $originalName, $srcPath ) {
 782                 $date = gmdate( "YmdHis" );
 783                 $hashPath = $this->getHashPath( $originalName );
 784                 $dstRel = "{$hashPath}{$date}!{$originalName}";
 785                 $dstUrlRel = $hashPath . $date . '!' . rawurlencode( $originalName );
 786
 787                 $result = $this->store( $srcPath, 'temp', $dstRel, self::SKIP_LOCKING );
 788                 $result->value = $this->getVirtualUrl( 'temp' ) . '/' . $dstUrlRel;
 789                 return $result;
 790         }
 791
 792         /**
 793          * Concatenate a list of files into a target file location.
 794          *
 795          * @param $srcPaths Array Ordered list of source virtual URLs/storage paths
 796          * @param $dstPath String Target virtual URL/storage path
 797          * @param $flags Integer: bitwise combination of the following flags:
 798          *     self::DELETE_SOURCE     Delete the source files
 799          * @return FileRepoStatus
 800          */
 801         function concatenate( $srcPaths, $dstPath, $flags = 0 ) {
 802                 $status = $this->newGood();
 803                 // Resolve target to a storage path if virtual
 804                 $dest = $this->resolveToStoragePath( $dstPath );
 805
 806                 $sources = array();
 807                 $deleteOperations = array(); // post-concatenate ops
 808                 foreach ( $srcPaths as $srcPath ) {
 809                         // Resolve source to a storage path if virtual
 810                         $source = $this->resolveToStoragePath( $srcPath );
 811                         $sources[] = $source; // chunk to merge
 812                         if ( $flags & self::DELETE_SOURCE ) {
 813                                 $deleteOperations[] = array( 'op' => 'delete', 'src' => $source );
 814                         }
 815                 }
 816
 817                 // Concatenate the chunks into one file
 818                 $op = array( 'op' => 'concatenate',
 819                         'srcs' => $sources, 'dst' => $dest, 'overwriteDest' => true );
 820                 $status->merge( $this->backend->doOperation( $op ) );
 821                 if ( !$status->isOK() ) {
 822                         return $status;
 823                 }
 824
 825                 // Delete the sources if required
 826                 if ( $deleteOperations ) {
 827                         $opts = array( 'ignoreErrors' => true );
 828                         $status->merge( $this->backend->doOperations( $deleteOperations, $opts ) );
 829                 }
 830
 831                 // Make sure status is OK, despite any $deleteOperations fatals
 832                 $status->setResult( true );
 833
 834                 return $status;
 835         }
 836
 837         /**
 838          * Remove a temporary file or mark it for garbage collection
 839          *
 840          * @param $virtualUrl String: the virtual URL returned by storeTemp
 841          * @return Boolean: true on success, false on failure
 842          */
 843         public function freeTemp( $virtualUrl ) {
 844                 $temp = "mwrepo://{$this->name}/temp";
 845                 if ( substr( $virtualUrl, 0, strlen( $temp ) ) != $temp ) {
 846                         wfDebug( __METHOD__.": Invalid temp virtual URL\n" );
 847                         return false;
 848                 }
 849                 $path = $this->resolveVirtualUrl( $virtualUrl );
 850                 $op = array( 'op' => 'delete', 'src' => $path );
 851                 $status = $this->backend->doOperation( $op );
 852                 return $status->isOK();
 853         }
 854
 855         /**
 856          * Copy or move a file either from a storage path, virtual URL,
 857          * or FS path, into this repository at the specified destination location.
 858          *
 859          * Returns a FileRepoStatus object. On success, the value contains "new" or
 860          * "archived", to indicate whether the file was new with that name.
 861          *
 862          * @param $srcPath String: the source FS path, storage path, or URL
 863          * @param $dstRel String: the destination relative path
 864          * @param $archiveRel String: the relative path where the existing file is to
 865          *        be archived, if there is one. Relative to the public zone root.
 866          * @param $flags Integer: bitfield, may be FileRepo::DELETE_SOURCE to indicate
 867          *        that the source file should be deleted if possible
 868          */
 869         public function publish( $srcPath, $dstRel, $archiveRel, $flags = 0 ) {
 870                 $status = $this->publishBatch( array( array( $srcPath, $dstRel, $archiveRel ) ), $flags );
 871                 if ( $status->successCount == 0 ) {
 872                         $status->ok = false;
 873                 }
 874                 if ( isset( $status->value[0] ) ) {
 875                         $status->value = $status->value[0];
 876                 } else {
 877                         $status->value = false;
 878                 }
 879                 return $status;
 880         }
 881
 882         /**
 883          * Publish a batch of files
 884          *
 885          * @param $triplets Array: (source, dest, archive) triplets as per publish()
 886          * @param $flags Integer: bitfield, may be FileRepo::DELETE_SOURCE to indicate
 887          *        that the source files should be deleted if possible
 888          * @return FileRepoStatus
 889          */
 890         public function publishBatch( $triplets, $flags = 0 ) {
 891                 $backend = $this->backend; // convenience
 892
 893                 // Try creating directories
 894                 $status = $this->initZones( 'public' );
 895                 if ( !$status->isOK() ) {
 896                         return $status;
 897                 }
 898
 899                 $status = $this->newGood( array() );
 900
 901                 $operations = array();
 902                 $sourceFSFilesToDelete = array(); // cleanup for disk source files
 903                 // Validate each triplet and get the store operation...
 904                 foreach ( $triplets as $i => $triplet ) {
 905                         list( $srcPath, $dstRel, $archiveRel ) = $triplet;
 906                         // Resolve source to a storage path if virtual
 907                         if ( substr( $srcPath, 0, 9 ) == 'mwrepo://' ) {
 908                                 $srcPath = $this->resolveVirtualUrl( $srcPath );
 909                         }
 910                         if ( !$this->validateFilename( $dstRel ) ) {
 911                                 throw new MWException( 'Validation error in $dstRel' );
 912                         }
 913                         if ( !$this->validateFilename( $archiveRel ) ) {
 914                                 throw new MWException( 'Validation error in $archiveRel' );
 915                         }
 916
 917                         $publicRoot = $this->getZonePath( 'public' );
 918                         $dstPath = "$publicRoot/$dstRel";
 919                         $archivePath = "$publicRoot/$archiveRel";
 920
 921                         $dstDir = dirname( $dstPath );
 922                         $archiveDir = dirname( $archivePath );
 923                         // Abort immediately on directory creation errors since they're likely to be repetitive
 924                         if ( !$backend->prepare( array( 'dir' => $dstDir ) )->isOK() ) {
 925                                 return $this->newFatal( 'directorycreateerror', $dstDir );
 926                         }
 927                         if ( !$backend->prepare( array( 'dir' => $archiveDir ) )->isOK() ) {
 928                                 return $this->newFatal( 'directorycreateerror', $archiveDir );
 929                         }
 930
 931                         // Archive destination file if it exists
 932                         if ( $backend->fileExists( array( 'src' => $dstPath ) ) ) {
 933                                 // Check if the archive file exists
 934                                 // This is a sanity check to avoid data loss. In UNIX, the rename primitive
 935                                 // unlinks the destination file if it exists. DB-based synchronisation in
 936                                 // publishBatch's caller should prevent races. In Windows there's no
 937                                 // problem because the rename primitive fails if the destination exists.
 938                                 if ( $backend->fileExists( array( 'src' => $archivePath ) ) ) {
 939                                         $operations[] = array( 'op' => 'null' );
 940                                         continue;
 941                                 } else {
 942                                         $operations[] = array(
 943                                                 'op'           => 'move',
 944                                                 'src'          => $dstPath,
 945                                                 'dst'          => $archivePath
 946                                         );
 947                                 }
 948                                 $status->value[$i] = 'archived';
 949                         } else {
 950                                 $status->value[$i] = 'new';
 951                         }
 952                         // Copy (or move) the source file to the destination
 953                         if ( FileBackend::isStoragePath( $srcPath ) ) {
 954                                 if ( $flags & self::DELETE_SOURCE ) {
 955                                         $operations[] = array(
 956                                                 'op'           => 'move',
 957                                                 'src'          => $srcPath,
 958                                                 'dst'          => $dstPath
 959                                         );
 960                                 } else {
 961                                         $operations[] = array(
 962                                                 'op'           => 'copy',
 963                                                 'src'          => $srcPath,
 964                                                 'dst'          => $dstPath
 965                                         );
 966                                 }
 967                         } else { // FS source path
 968                                 $operations[] = array(
 969                                         'op'           => 'store',
 970                                         'src'          => $srcPath,
 971                                         'dst'          => $dstPath
 972                                 );
 973                                 if ( $flags & self::DELETE_SOURCE ) {
 974                                         $sourceFSFilesToDelete[] = $srcPath;
 975                                 }
 976                         }
 977                 }
 978
 979                 // Execute the operations for each triplet
 980                 $opts = array( 'ignoreErrors' => true );
 981                 $status->merge( $backend->doOperations( $operations, $opts ) );
 982                 // Cleanup for disk source files...
 983                 foreach ( $sourceFSFilesToDelete as $file ) {
 984                         wfSuppressWarnings();
 985                         unlink( $file ); // FS cleanup
 986                         wfRestoreWarnings();
 987                 }
 988
 989                 return $status;
 990         }
 991
 992         /**
 993          * Checks existence of a a file
 994          *
 995          * @param $file Virtual URL (or storage path) of file to check
 996          * @param $flags Integer: bitwise combination of the following flags:
 997          *     self::FILES_ONLY     Mark file as existing only if it is a file (not directory)
 998          * @return bool
 999          */
1000         public function fileExists( $file, $flags = 0 ) {
1001                 $result = $this->fileExistsBatch( array( $file ), $flags );
1002                 return $result[0];
1003         }
1004
1005         /**
1006          * Checks existence of an array of files.
1007          *
1008          * @param $files Array: Virtual URLs (or storage paths) of files to check
1009          * @param $flags Integer: bitwise combination of the following flags:
1010          *     self::FILES_ONLY     Mark file as existing only if it is a file (not directory)
1011          * @return Either array of files and existence flags, or false
1012          */
1013         public function fileExistsBatch( $files, $flags = 0 ) {
1014                 $result = array();
1015                 foreach ( $files as $key => $file ) {
1016                         if ( self::isVirtualUrl( $file ) ) {
1017                                 $file = $this->resolveVirtualUrl( $file );
1018                         }
1019                         if ( FileBackend::isStoragePath( $file ) ) {
1020                                 $result[$key] = $this->backend->fileExists( array( 'src' => $file ) );
1021                         } else {
1022                                 if ( $flags & self::FILES_ONLY ) {
1023                                         $result[$key] = is_file( $file ); // FS only
1024                                 } else {
1025                                         $result[$key] = file_exists( $file ); // FS only
1026                                 }
1027                         }
1028                 }
1029
1030                 return $result;
1031         }
1032
1033         /**
1034          * Move a file to the deletion archive.
1035          * If no valid deletion archive exists, this may either delete the file
1036          * or throw an exception, depending on the preference of the repository
1037          *
1038          * @param $srcRel Mixed: relative path for the file to be deleted
1039          * @param $archiveRel Mixed: relative path for the archive location.
1040          *        Relative to a private archive directory.
1041          * @return FileRepoStatus object
1042          */
1043         public function delete( $srcRel, $archiveRel ) {
1044                 return $this->deleteBatch( array( array( $srcRel, $archiveRel ) ) );
1045         }
1046
1047         /**
1048          * Move a group of files to the deletion archive.
1049          *
1050          * If no valid deletion archive is configured, this may either delete the
1051          * file or throw an exception, depending on the preference of the repository.
1052          *
1053          * The overwrite policy is determined by the repository -- currently LocalRepo
1054          * assumes a naming scheme in the deleted zone based on content hash, as
1055          * opposed to the public zone which is assumed to be unique.
1056          *
1057          * @param $sourceDestPairs Array of source/destination pairs. Each element
1058          *        is a two-element array containing the source file path relative to the
1059          *        public root in the first element, and the archive file path relative
1060          *        to the deleted zone root in the second element.
1061          * @return FileRepoStatus
1062          */
1063         public function deleteBatch( $sourceDestPairs ) {
1064                 $backend = $this->backend; // convenience
1065
1066                 if ( !isset( $this->zones['deleted']['container'] ) ) {
1067                         throw new MWException( __METHOD__.': no valid deletion archive directory' );
1068                 }
1069
1070                 // Try creating directories
1071                 $status = $this->initZones( array( 'public', 'deleted' ) );
1072                 if ( !$status->isOK() ) {
1073                         return $status;
1074                 }
1075
1076                 $status = $this->newGood();
1077
1078                 $operations = array();
1079                 // Validate filenames and create archive directories
1080                 foreach ( $sourceDestPairs as $pair ) {
1081                         list( $srcRel, $archiveRel ) = $pair;
1082                         if ( !$this->validateFilename( $srcRel ) ) {
1083                                 throw new MWException( __METHOD__.':Validation error in $srcRel' );
1084                         }
1085                         if ( !$this->validateFilename( $archiveRel ) ) {
1086                                 throw new MWException( __METHOD__.':Validation error in $archiveRel' );
1087                         }
1088
1089                         $publicRoot = $this->getZonePath( 'public' );
1090                         $srcPath = "{$publicRoot}/$srcRel";
1091
1092                         $deletedRoot = $this->getZonePath( 'deleted' );
1093                         $archivePath = "{$deletedRoot}/{$archiveRel}";
1094                         $archiveDir = dirname( $archivePath ); // does not touch FS
1095
1096                         // Create destination directories
1097                         if ( !$backend->prepare( array( 'dir' => $archiveDir ) )->isOK() ) {
1098                                 return $this->newFatal( 'directorycreateerror', $archiveDir );
1099                         }
1100                         $this->initDeletedDir( $archiveDir );
1101
1102                         if ( $backend->fileExists( array( 'src' => $archivePath ) ) ) {
1103                                 $operations[] = array(
1104                                         'op'  => 'delete',
1105                                         'src' => $srcPath
1106                                 );
1107                         } else {
1108                                 $operations[] = array(
1109                                         'op'  => 'move',
1110                                         'src' => $srcPath,
1111                                         'dst' => $archivePath
1112                                 );
1113                         }
1114                 }
1115
1116                 // Move the files by execute the operations for each pair.
1117                 // We're now committed to returning an OK result, which will
1118                 // lead to the files being moved in the DB also.
1119                 $opts = array( 'ignoreErrors' => true );
1120                 $status->merge( $backend->doOperations( $operations, $opts ) );
1121
1122                 return $status;
1123         }
1124
1125         /**
1126          * Get a relative path for a deletion archive key,
1127          * e.g. s/z/a/ for sza251lrxrc1jad41h5mgilp8nysje52.jpg
1128          *
1129          * @return string
1130          */
1131         public function getDeletedHashPath( $key ) {
1132                 $path = '';
1133                 for ( $i = 0; $i < $this->deletedHashLevels; $i++ ) {
1134                         $path .= $key[$i] . '/';
1135                 }
1136                 return $path;
1137         }
1138
1139         /**
1140          * If a path is a virtual URL, resolve it to a storage path.
1141          * Otherwise, just return the path as it is.
1142          *
1143          * @param $path string
1144          * @return string
1145          * @throws MWException
1146          */
1147         protected function resolveToStoragePath( $path ) {
1148                 if ( $this->isVirtualUrl( $path ) ) {
1149                         return $this->resolveVirtualUrl( $path );
1150                 }
1151                 return $path;
1152         }
1153
1154         /**
1155          * Get a local FS copy of a file with a given virtual URL/storage path.
1156          * Temporary files may be purged when the file object falls out of scope.
1157          *
1158          * @param $virtualUrl string
1159          * @return TempFSFile|null Returns null on failure
1160          */
1161         public function getLocalCopy( $virtualUrl ) {
1162                 $path = $this->resolveToStoragePath( $virtualUrl );
1163                 return $this->backend->getLocalCopy( array( 'src' => $path ) );
1164         }
1165
1166         /**
1167          * Get a local FS file with a given virtual URL/storage path.
1168          * The file is either an original or a copy. It should not be changed.
1169          * Temporary files may be purged when the file object falls out of scope.
1170          *
1171          * @param $virtualUrl string
1172          * @return FSFile|null Returns null on failure.
1173          */
1174         public function getLocalReference( $virtualUrl ) {
1175                 $path = $this->resolveToStoragePath( $virtualUrl );
1176                 return $this->backend->getLocalReference( array( 'src' => $path ) );
1177         }
1178
1179         /**
1180          * Get properties of a file with a given virtual URL/storage path.
1181          * Properties should ultimately be obtained via FSFile::getProps().
1182          *
1183          * @param $virtualUrl string
1184          * @return Array
1185          */
1186         public function getFileProps( $virtualUrl ) {
1187                 $path = $this->resolveToStoragePath( $virtualUrl );
1188                 return $this->backend->getFileProps( array( 'src' => $path ) );
1189         }
1190
1191         /**
1192          * Get the timestamp of a file with a given virtual URL/storage path
1193          *
1194          * @param $virtualUrl string
1195          * @return string|false
1196          */
1197         public function getFileTimestamp( $virtualUrl ) {
1198                 $path = $this->resolveToStoragePath( $virtualUrl );
1199                 return $this->backend->getFileTimestamp( array( 'src' => $path ) );
1200         }
1201
1202         /**
1203          * Get the sha1 of a file with a given virtual URL/storage path
1204          *
1205          * @param $virtualUrl string
1206          * @return string|false
1207          */
1208         public function getFileSha1( $virtualUrl ) {
1209                 $path = $this->resolveToStoragePath( $virtualUrl );
1210                 $tmpFile = $this->backend->getLocalReference( array( 'src' => $path ) );
1211                 if ( !$tmpFile ) {
1212                         return false;
1213                 }
1214                 return $tmpFile->getSha1Base36();
1215         }
1216
1217         /**
1218          * Attempt to stream a file with the given virtual URL/storage path
1219          *
1220          * @param $virtualUrl string
1221          * @param $headers Array Additional HTTP headers to send on success
1222          * @return bool Success
1223          */
1224         public function streamFile( $virtualUrl, $headers = array() ) {
1225                 $path = $this->resolveToStoragePath( $virtualUrl );
1226                 $params = array( 'src' => $path, 'headers' => $headers );
1227                 return $this->backend->streamFile( $params )->isOK();
1228         }
1229
1230         /**
1231          * Call a callback function for every public file in the repository.
1232          * May use either the database or the filesystem.
1233          *
1234          * @param $callback Array|string
1235          * @return void
1236          */
1237         public function enumFiles( $callback ) {
1238                 return $this->enumFilesInStorage( $callback );
1239         }
1240
1241         /**
1242          * Call a callback function for every public file in the repository.
1243          * May use either the database or the filesystem.
1244          *
1245          * @param $callback Array|string
1246          * @return void
1247          */
1248         protected function enumFilesInStorage( $callback ) {
1249                 $publicRoot = $this->getZonePath( 'public' );
1250                 $numDirs = 1 << ( $this->hashLevels * 4 );
1251                 // Use a priori assumptions about directory structure
1252                 // to reduce the tree height of the scanning process.
1253                 for ( $flatIndex = 0; $flatIndex < $numDirs; $flatIndex++ ) {
1254                         $hexString = sprintf( "%0{$this->hashLevels}x", $flatIndex );
1255                         $path = $publicRoot;
1256                         for ( $hexPos = 0; $hexPos < $this->hashLevels; $hexPos++ ) {
1257                                 $path .= '/' . substr( $hexString, 0, $hexPos + 1 );
1258                         }
1259                         $iterator = $this->backend->getFileList( array( 'dir' => $path ) );
1260                         foreach ( $iterator as $name ) {
1261                                 // Each item returned is a public file
1262                                 call_user_func( $callback, "{$path}/{$name}" );
1263                         }
1264                 }
1265         }
1266
1267         /**
1268          * Determine if a relative path is valid, i.e. not blank or involving directory traveral
1269          *
1270          * @param $filename string
1271          * @return bool
1272          */
1273         public function validateFilename( $filename ) {
1274                 if ( strval( $filename ) == '' ) {
1275                         return false;
1276                 }
1277                 if ( wfIsWindows() ) {
1278                         $filename = strtr( $filename, '\\', '/' );
1279                 }
1280                 /**
1281                  * Use the same traversal protection as Title::secureAndSplit()
1282                  */
1283                 if ( strpos( $filename, '.' ) !== false &&
1284                         ( $filename === '.' || $filename === '..' ||
1285                                 strpos( $filename, './' ) === 0  ||
1286                                 strpos( $filename, '../' ) === 0 ||
1287                                 strpos( $filename, '/./' ) !== false ||
1288                                 strpos( $filename, '/../' ) !== false ) )
1289                 {
1290                         return false;
1291                 } else {
1292                         return true;
1293                 }
1294         }
1295
1296         /**
1297          * Get a callback function to use for cleaning error message parameters
1298          *
1299          * @return Array
1300          */
1301         function getErrorCleanupFunction() {
1302                 switch ( $this->pathDisclosureProtection ) {
1303                         case 'none':
1304                                 $callback = array( $this, 'passThrough' );
1305                                 break;
1306                         case 'simple':
1307                                 $callback = array( $this, 'simpleClean' );
1308                                 break;
1309                         default: // 'paranoid'
1310                                 $callback = array( $this, 'paranoidClean' );
1311                 }
1312                 return $callback;
1313         }
1314
1315         /**
1316          * Path disclosure protection function
1317          *
1318          * @param $param string
1319          * @return string
1320          */
1321         function paranoidClean( $param ) {
1322                 return '[hidden]';
1323         }
1324
1325         /**
1326          * Path disclosure protection function
1327          *
1328          * @param $param string
1329          * @return string
1330          */
1331         function simpleClean( $param ) {
1332                 global $IP;
1333                 if ( !isset( $this->simpleCleanPairs ) ) {
1334                         $this->simpleCleanPairs = array(
1335                                 $IP => '$IP', // sanity
1336                         );
1337                 }
1338                 return strtr( $param, $this->simpleCleanPairs );
1339         }
1340
1341         /**
1342          * Path disclosure protection function
1343          *
1344          * @param $param string
1345          * @return string
1346          */
1347         function passThrough( $param ) {
1348                 return $param;
1349         }
1350
1351         /**
1352          * Create a new fatal error
1353          *
1354          * @return FileRepoStatus
1355          */
1356         function newFatal( $message /*, parameters...*/ ) {
1357                 $params = func_get_args();
1358                 array_unshift( $params, $this );
1359                 return MWInit::callStaticMethod( 'FileRepoStatus', 'newFatal', $params );
1360         }
1361
1362         /**
1363          * Create a new good result
1364          *
1365          * @return FileRepoStatus
1366          */
1367         function newGood( $value = null ) {
1368                 return FileRepoStatus::newGood( $this, $value );
1369         }
1370
1371         /**
1372          * Delete files in the deleted directory if they are not referenced in the filearchive table
1373          *
1374          * STUB
1375          */
1376         public function cleanupDeletedBatch( $storageKeys ) {}
1377
1378         /**
1379          * Checks if there is a redirect named as $title. If there is, return the
1380          * title object. If not, return false.
1381          * STUB
1382          *
1383          * @param $title Title of image
1384          * @return Bool
1385          */
1386         public function checkRedirect( Title $title ) {
1387                 return false;
1388         }
1389
1390         /**
1391          * Invalidates image redirect cache related to that image
1392          * Doesn't do anything for repositories that don't support image redirects.
1393          *
1394          * STUB
1395          * @param $title Title of image
1396          */
1397         public function invalidateImageRedirect( Title $title ) {}
1398
1399         /**
1400          * Get the human-readable name of the repo
1401          *
1402          * @return string
1403          */
1404         public function getDisplayName() {
1405                 // We don't name our own repo, return nothing
1406                 if ( $this->isLocal() ) {
1407                         return null;
1408                 }
1409                 // 'shared-repo-name-wikimediacommons' is used when $wgUseInstantCommons = true
1410                 return wfMessageFallback( 'shared-repo-name-' . $this->name, 'shared-repo' )->text();
1411         }
1412
1413         /**
1414          * Returns true if this the local file repository.
1415          *
1416          * @return bool
1417          */
1418         public function isLocal() {
1419                 return $this->getName() == 'local';
1420         }
1421
1422         /**
1423          * Get a key on the primary cache for this repository.
1424          * Returns false if the repository's cache is not accessible at this site.
1425          * The parameters are the parts of the key, as for wfMemcKey().
1426          *
1427          * STUB
1428          */
1429         function getSharedCacheKey( /*...*/ ) {
1430                 return false;
1431         }
1432
1433         /**
1434          * Get a key for this repo in the local cache domain. These cache keys are
1435          * not shared with remote instances of the repo.
1436          * The parameters are the parts of the key, as for wfMemcKey().
1437          *
1438          * @return string
1439          */
1440         function getLocalCacheKey( /*...*/ ) {
1441                 $args = func_get_args();
1442                 array_unshift( $args, 'filerepo', $this->getName() );
1443                 return call_user_func_array( 'wfMemcKey', $args );
1444         }
1445
1446         /**
1447          * Get an UploadStash associated with this repo.
1448          *
1449          * @return UploadStash
1450          */
1451         public function getUploadStash() {
1452                 return new UploadStash( $this );
1453         }
1454 }